---
title: Zoi
description: Universal Package Manager & Environment Setup Tool.
---

This guide will provide you with everything you need to know to get started, from installation to advanced usage.

## Nel Package Registry

Zoi provides an online package registry, the [Nel Registry](https://nel.zillowe.qzz.io), to help you discover and search for packages. It provides a user-friendly web interface to browse all the packages available in the official Zoi repositories.

[Repository](https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi)

## Introduction

Zoi is a universal package manager and environment setup tool, designed to simplify package management and environment configuration across multiple operating systems. It's part of the [Zillowe Development Suite (ZDS)](/docs/zds) and aims to streamline your development workflow by managing tools and project environments with ease.

## Features

- **Cross-Platform:** Works seamlessly on Linux, macOS, and Windows.
- **Dynamic Package Definitions:** Define packages with dynamic Lua scripts (`.pkg.lua`) for maximum flexibility.
- **Universal Package Support:** Install from binaries, compressed archives, source, or installer scripts.
- **Extensive Dependency Management:** Integrates with over 40 package managers (`apt`, `brew`, `cargo`, `npm`, `pip`, etc.).
- **Rich Dependencies:** Define runtime and build dependencies with required, optional, and selectable options.
- **Project Environments:** Manage project-specific commands and environments with `zoi.yaml`.
- **Repository-Based:** Use official, community, or your own private/public Git-based repositories.
- **Secure & Verifiable:** Verifies package integrity and authenticity with checksums and GPG signatures. Manage keys with `zoi pgp`.
- **Versatile Package Types:** Supports standard packages, collections, services, configs, app templates, extensions, libraries, and inline scripts.
- **Local Package Development:** A dedicated `zoi package` command set (`meta`, `build`, `install`) to streamline creating and testing packages locally.
- **Advanced CLI Tools:**
  - `zoi man`: Read package manuals in the terminal.
  - `zoi why`: Understand why a package is installed.
  - `zoi rollback`: Revert a package to its previous version.
  - `zoi pin`: Pin a package to a specific version.
  - `zoi exec`: Run a package without installing it.
- **Library Support:** Use as a Rust library and get compiler/linker flags via `zoi pkg-config`.

## Getting Started

Getting started with Zoi is simple. Just follow these three steps:

1.  **Install Zoi:**
    Choose one of the [installation methods](#installation) below.

2.  **Sync Repositories:**
    Before you can install packages, you need to sync the package repositories.

    ```sh
    zoi sync
    ```

3.  **Install a Package:**
    Now you can install any package you want. For example, to install `hello`:

    ```sh
    zoi install hello
    ```

## Installation

You can install Zoi using a package manager, an installer script, or by building it from source.

### Scripts

You can also use our installer scripts for a quick setup.

**Linux / macOS :**

```sh
curl -fsSL https://zillowe.pages.dev/scripts/zoi/install.sh | bash
```

**Windows:**

```powershell
powershell -c "irm zillowe.pages.dev/scripts/zoi/install.ps1|iex"
```

### Package Managers

#### Linux

Install Zoi on Linux distros.

##### Arch Linux (AUR)

Install [`zoi-bin`](https://aur.archlinux.org/packages/zoi-bin) (Pre-compiled binary) or [`zoi`](https://aur.archlinux.org/packages/zoi) (built from source) from the AUR using your favorite helper (e.g. `yay`, `paru`):

```sh
yay -S zoi-bin
```

Or manually without any helpers:

```sh
git clone https://aur.archlinux.org/zoi-bin.git
cd zoi-bin
makepkg -si
```

##### Fedora

Install `zoi-rs` on Fedora from [Terra](https://terra.fyralabs.com) repo (not maintained by us, uses [Crates.io](#cratesio) so may not be up-to-date):

```sh
# add terra repo
dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
# install Zoi
sudo dnf install zoi-rs
```

More information and instructions for using Terra are available [here](https://developer.fyralabs.com/terra/installing).

#### macOS

Install Zoi on macOS.

##### Homebrew

Install Zoi using Homebrew (Also supports linux):

```sh
brew install Zillowe/tap/zoi
```

#### Windows

Install Zoi on Windows.

##### Scoop

Install Zoi using Scoop:

```powershell
scoop bucket add zillowe https://github.com/Zillowe/scoop.git
scoop install zoi
```

#### Crates.io

You can install `zoi` directly from [crates.io](https://crates.io/crates/zoi-rs) using `cargo`:

```sh
cargo install zoi-rs
```

#### NPM

You can install `@zillowe/zoi` from `npm` also.

<Tabs defaultValue="npm">
  <TabsList>
    <TabsTrigger value="npm">
      <FaNpm />
      npm
    </TabsTrigger>
    <TabsTrigger value="bun">
      <svg
        xmlns="http://www.w3.org/2000/svg"
        width={24}
        height={24}
        fill={"currentColor"}
        viewBox="0 0 24 24"
      >
        <path d="m9.34,7.66c-.07.06-.02.18.08.15.85-.33,2.01-1.32,1.52-3.33-.02-.11-.17-.08-.17.02,0,1.21-.51,2.36-1.43,3.16Z"></path>
        <path d="m11.34,4.51c.63,1.02.78,2.27.41,3.41-.03.09.08.16.14.09.55-.71,1.04-2.12-.41-3.64-.07-.07-.19.04-.14.12h0Z"></path>
        <path d="m12.04,4.46c.98.69,1.61,1.78,1.73,2.98,0,.05.03.09.07.09.04,0,.08-.02.09-.07.23-.88.1-2.39-1.82-3.17-.1-.04-.17.1-.08.16h0Z"></path>
        <path d="m7.37,7.26c.91.06,2.38-.37,2.82-2.39.02-.1-.12-.14-.17-.05-.52,1.1-1.48,1.93-2.65,2.28-.09.03-.09.16,0,.16Z"></path>
        <path d="m19.87,8.36s-.08-.09-.13-.13c-.04-.04-.08-.09-.13-.13-.04-.04-.08-.09-.13-.13-.04-.04-.08-.09-.13-.13-.04-.04-.08-.09-.13-.13-.04-.04-.08-.09-.13-.12h0s0,0,0,0c-.02-.02-.04-.04-.06-.06-.62-.65-1.37-1.23-2.25-1.7-.94-.5-1.65-.94-2.28-1.33-.27-.17-.52-.33-.78-.47-.83-.49-1.49-.79-2.25-.79s-1.52.35-2.41.88c-.29.17-.59.36-.91.55-.58.36-1.23.76-1.99,1.17-2.62,1.42-4.18,3.78-4.18,6.31,0,1.86.84,3.56,2.22,4.88l.1.1.76.76c1.74,1.75,4.42,2.88,7.43,2.88,5.24,0,9.49-3.41,9.49-7.59,0-1.79-.77-3.48-2.13-4.81Zm-8.38,10.76c-4.89,0-8.86-3.13-8.86-6.97,0-2.3,1.44-4.45,3.85-5.75.76-.41,1.44-.83,2.03-1.19.31-.19.61-.38.9-.54.82-.48,1.48-.79,2.09-.79s1.17.25,1.94.71c.23.14.48.3.76.47.61.37,1.35.85,2.31,1.36,2.41,1.3,3.85,3.45,3.85,5.75,0,3.85-3.97,6.97-8.86,6.97Z"></path>
        <path d="m13.08,13.65h-3.12c-.11,0-.22.04-.29.13-.06.07-.08.16-.07.25.12.5.4.95.79,1.28.31.29.7.47,1.13.51.42-.04.82-.22,1.12-.51.39-.33.67-.78.79-1.28.02-.09,0-.18-.06-.25-.07-.08-.18-.13-.29-.13Zm-1.56,1.87c-.35-.04-.67-.2-.92-.44-.02-.02-.04-.04-.06-.06.26-.33.65-.52,1.07-.53.38.01.74.16,1.01.43-.05.06-.11.12-.17.17-.25.24-.58.4-.92.44Z"></path>
        <path d="m8.38,10.14c-.77,0-1.4.62-1.4,1.39h0c0,.77.62,1.4,1.39,1.4.77,0,1.4-.62,1.4-1.39,0-.77-.62-1.4-1.39-1.4Zm-.44,1.48c-.29,0-.52-.24-.52-.52h0c0-.29.24-.53.53-.52.29,0,.52.24.52.53,0,.29-.24.52-.53.52Z"></path>
        <path d="m14.67,10.14c-.77,0-1.4.61-1.41,1.38,0,0,0,0,0,.01,0,.77.62,1.39,1.38,1.39.77,0,1.4-.61,1.41-1.38s-.61-1.4-1.38-1.41Zm-.45,1.48h0c-.29,0-.52-.24-.52-.52h0c0-.29.24-.53.53-.52.29,0,.52.24.52.53,0,.29-.24.52-.53.52Z"></path>
      </svg>
      bun
    </TabsTrigger>
    <TabsTrigger value="pnpm">
      <TbBrandPnpm />
      pnpm
    </TabsTrigger>
    <TabsTrigger value="yarn">
      <FaYarn />
      yarn
    </TabsTrigger>
  </TabsList>
  <TabsContent value="npm">

    ```sh
    npx @zillowe/zoi
    ```

  </TabsContent>
  <TabsContent value="bun">

    ```sh
    bunx @zillowe/zoi
    ```

</TabsContent>
  <TabsContent value="pnpm">

    ```sh
    pnpm dlx @zillowe/zoi
    ```

</TabsContent>
  <TabsContent value="yarn">

    ```sh
    yarn dlx @zillowe/zoi
    ```

</TabsContent>
</Tabs>

### Build from Source

If you prefer, you can build Zoi from source. You'll need [Rust](https://www.rust-lang.org) installed.

**Build the release binary:**

```sh
# For Linux/macOS
./scripts/build-release.sh

# For Windows
./scripts/build-release.ps1
```

**Install it locally:**

```sh
./configure
make build
sudo make install
# (optional) Install CLI completions and setup Zoi's PATH
make setup
```

## Platforms

What platforms we currently support.

| OS      | Arch  | Zoi Binary | Packages Support |
| ------- | ----- | ---------- | ---------------- |
| Linux   | amd64 | ✔️         | ✔️               |
| Linux   | arm64 | ✔️         | ✔️               |
| macOS   | amd64 | ✔️         | ✔️               |
| macOS   | arm64 | ✔️         | ✔️               |
| Windows | amd64 | ✔️         | ✔️               |
| Windows | arm64 | ❌         | ✔️               |
| FreeBSD | amd64 | ❌         | ✔️               |
| FreeBSD | arm64 | ❌         | ✔️               |
| OpenBSD | amd64 | ❌         | ✔️               |
| OpenBSD | arm64 | ❌         | ✔️               |

We're planning to add support for more platforms.

## Usage & Commands

Zoi provides a wide range of commands to manage your packages and environment. For a full list of commands and their options, you can always run `zoi --help`.

### General Commands

| Command      | Description                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`    | Displays the version number, build status, branch, and commit hash.                                                                                                                                                                                                                                                                                                                            |
| `about`      | Displays the full application name, description, author, license, and homepage.                                                                                                                                                                                                                                                                                                                |
| `info`       | Displays key system details like OS, CPU architecture, and available package managers (requires `zoi sync` to be run first for package manager detection).                                                                                                                                                                                                                                     |
| `check`      | Verifies that all required dependencies (like git) are installed.                                                                                                                                                                                                                                                                                                                              |
| `setup`      | Configures the shell environment for Zoi to make package binaries available. <br/>`--scope <user                                                                                                                                                                                                                                                      system>`: Set the scope (default: user). |
| `sync`       | Clones or updates the package database from the configured registry. <br/>`--verbose`: Show the full git output. <br/>`--fallback`: If the primary registry fails, try to sync from official mirrors (GitHub, Codeberg, GitLab). <br/>`--no-pm`: Skip checking for installed package managers.                                                                                                 |
| `upgrade`    | Downloads the latest release of Zoi and replaces the current executable. <br/>`--full`: Force a full download, skipping the patch-based upgrade. <br/>`--force`: Force the upgrade even if the version is the same. <br/>`--tag <tag>`: Upgrade to a specific git tag. <br/>`--branch <branch>`: Upgrade to the latest release of a specific branch.                                           |
| `clean`      | Clears the cache of downloaded package binaries.                                                                                                                                                                                                                                                                                                                                               |
| `autoremove` | Removes packages that were installed as dependencies but are no longer needed.                                                                                                                                                                                                                                                                                                                 |
| `telemetry`  | Manages [opt-in telemetry](./telemetry).                                                                                                                                                                                                                                                                                                                                                       |

### Package Management

| Command      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list`       | Lists installed or all available packages. <br/>`--all`: List all packages, not just installed. <br/>`--repo <repo>`: Filter by repository. <br/>`--type <type>`: Filter by package type.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `show`       | Shows detailed information about a package. <br/>`--raw`: Display the raw, unformatted package file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `search`     | Searches packages by name, description, and tags. <br/>`--repo <repo>`: Filter by repository. <br/>`--type <type>`: Filter by package type. <br/>`-t, --tag <tag>`: Filter by one or more tags (repeat or comma-separate).                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `shell`      | Installs completion scripts for a given shell (e.g. `zoi shell bash`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `install`    | Installs one or more packages. Can also install from a `zoi.pkgs.json` file (to restore all packages) or a `<pkg>.manifest.yaml` file (for reproducible dependency choices). <br/>`--repo <repo>`: Install a package directly from a git repository (e.g. `Zillowe/Hello` or `gl:Zillowe/Hello`). The repository must contain a `zoi.yaml` file with a `package` field specifying a package name, a path to a `.pkg.lua` file, or a URL to one. <br/>`--force`: Force re-installation if the package already exists. <br/>`--interactive`: Choose the installation method interactively. <br/>`--all-optional`: Install all optional dependencies. |
| `build`      | Builds and installs one or more packages from source. <br/>`--force`: Force the package to be rebuilt.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `uninstall`  | Removes one or more packages. Also removes any of its dependencies that are no longer needed. For collections, it removes all of its dependencies.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `update`     | Updates one or more packages to the latest version.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `pin`        | Pins a package to a specific version to prevent updates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `unpin`      | Unpins a package, allowing it to be updated again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `rollback`   | Rolls back a package to its previously installed version. See [Package Rollbacks](/docs/zds/zoi/rollbacks).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `why`        | Explains why a package is installed (e.g. as a dependency or directly).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `clone`      | Clones the source code repository of one or more packages. A target directory can only be specified when cloning a single package.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `exec`       | Downloads a binary to a temporary cache and runs it without installing it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `extension`  | Manages Zoi extensions (`add`, `remove`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `create`     | Creates an application from an app template. Usage: `zoi create <source> <appName>`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `man`        | Renders a package's manual in the terminal. <br/>`--upstream`: Fetch the manual from its remote URL, ignoring any local copy. <br/>`--raw`: Print the raw manual content without rendering.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `pkg-config` | Provides compiler and linker flags for installed libraries.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

### Project Environment

| Command | Description                                                                    |
| ------- | ------------------------------------------------------------------------------ |
| `run`   | Executes a command from a local `zoi.yaml` file. Can be run interactively.     |
| `env`   | Sets up project environments from a `zoi.yaml` file. Can be run interactively. |

See the full schema and examples in [Project Configuration (zoi.yaml)](/docs/zds/zoi/project-config).

### Service Management

| Command | Description                         |
| ------- | ----------------------------------- |
| `start` | Starts a package that is a service. |
| `stop`  | Stops a running service package.    |

### Package Development

| Command   | Description                                                                   |
| --------- | ----------------------------------------------------------------------------- |
| `package` | Build, create, and manage Zoi packages (`meta`, `build`, `install`).          |
| `pgp`     | Manage PGP keys for package signature verification (`add`, `remove`, `list`). |

### Sync Management (`sync`)

Manages the package database registry URL.

| Subcommand                  | Description                                                                                  |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| `sync set <url or keyword>` | Sets the package database registry URL. Keywords: `default`, `gitlab`, `github`, `codeberg`. |
| `sync show`                 | Displays the current registry URL.                                                           |

### Repository Management (`repo`)

Manages the list of package repositories that Zoi uses.

| Subcommand                | Description                                                                     |
| ------------------------- | ------------------------------------------------------------------------------- |
| `repo add <name-or-url>`  | Add an official repo by name or clone from a git URL (interactive if no args).  |
| `repo rm <name>`          | Remove a repository from the active list.                                       |
| `repo ls`                 | Show active repositories. Use `repo ls all` to show all available repositories. |
| `repo git ls`             | List cloned git repositories under `~/.zoi/pkgs/git`.                           |
| `repo git rm <repo-name>` | Remove a cloned git repository directory (`~/.zoi/pkgs/git/<repo-name>`).       |

**Example:**

```sh
# Add a repository interactively
zoi repo add

# Add a repository by name
zoi repo add community

# Add a repository by git URL (auto-clone)
zoi repo add https://example.com/my-zoi-repo.git

# Remove a repository
zoi repo rm community

# List active repositories
zoi repo ls
```

For an overview of official repositories, mirrors, and repository tiers, see [Repositories](/docs/zds/zoi/repositories).

Zoi supports different types of packages, defined in the `.pkg.lua` file.

| Type         | Description                                                                                                                                                                                                                         |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Package`    | A standard software package that can be installed. This is the default type.                                                                                                                                                        |
| `Collection` | A meta-package that groups other packages together as dependencies.                                                                                                                                                                 |
| `Service`    | A package that runs as a background service. Can be managed with shell commands or via Docker Compose.                                                                                                                              |
| `Config`     | A package that manages configuration files. It includes commands for installing and uninstalling the configuration.                                                                                                                 |
| `App`        | An app template. Not installable; used via `zoi create` to scaffold an application (e.g. frameworks like Rails).                                                                                                                    |
| `Extension`  | A package that can modify Zoi's configuration, such as adding new package repositories. It is not installed in the traditional sense but its changes are applied or reverted. See the [Extensions Guide](/docs/zds/zoi/extensions). |
| `Library`    | A software library with headers and/or binaries (.so, .dll, .a). Can provide pkg-config files.                                                                                                                                      |
| `Script`     | A package that runs a series of inline shell commands instead of installing a binary.                                                                                                                                               |

## Creating Packages (`.pkg.lua`)

Packages for Zoi are defined using `.pkg.lua` files. These are Lua scripts that define package metadata and installation logic, allowing for highly dynamic and flexible package definitions.

- **Dynamic & Flexible:** Use Lua scripting to define dynamic URLs, platform-specific logic, and complex installation steps.
- **Comprehensive Examples:** For a deep dive into creating packages, see the [Creating Packages guide](/docs/zds/zoi/creating-packages) and the [Package Examples](/docs/zds/zoi/examples).

### `.pkg.lua` Structure

A `.pkg.lua` file is a Lua script that calls global functions like `package{}`, `install{}`, and `dependencies{}` to define the package.

```lua
-- my-cli.pkg.lua
package({
  name = "my-cli",
  repo = "community",
  version = "1.2.3",
  description = "A simple command-line utility.",
  -- ... more metadata
})

install({
  {
    type = "binary",
    url = "https://example.com/my-cli-v" .. PKG.version .. "-" .. SYSTEM.OS .. "-" .. SYSTEM.ARCH,
    platforms = { "all" },
  }
})
```

This approach allows you to use Lua's full power to construct your package definition. You have access to global variables like `PKG` (the package table) and `SYSTEM` (with `OS`, `ARCH`, `DISTRO`).

### Installation Methods

Zoi supports four types of installation methods within the `installation` list:

1.  **`binary`**: Downloads a pre-compiled binary directly from a URL.
2.  **`com_binary`**: Downloads a compressed archive (`.zip`, `.tar.gz`, etc.), extracts it, and finds the binary within. Supports `bin_path` to point to the executable inside the archive and a `files` field to copy additional files (e.g. manuals, licenses). On Windows targets, if `bin_path` lacks `.exe`, Zoi will also try with `.exe` appended.
3.  **`source`**: Clones a git repository and runs your defined `build_commands`. Zoi then moves the final executable to the installation directory. By default, Zoi looks for an executable with the same name as the package. If the executable has a different name or is in a subdirectory, you must specify its location with the `bin_path` field. Also supports a `files` field to copy additional files from the build directory. Supports optional `tag` or `branch` (use only one). If none is provided, the default branch HEAD is used. For reproducible builds, you can specify a `docker_image` to run the build inside a container.
4.  **`script`**: Downloads and executes an installation script (e.g. `install.sh`).

For the list of supported archive formats for `com_binary`, see [Supported Archives for Compressed Binaries](/docs/zds/zoi/archives).

### Dependencies

For the full list of supported dependency managers, usage semantics, and commands Zoi runs, see [Dependencies & Supported Package Managers](/docs/zds/zoi/dependencies).

## FAQ

<Accordions type="single">
  <Accordion title="How do I create my own package for Zoi?">
    You can create a `.pkg.lua` file that defines your package. This file includes metadata like the package name, version, description, and installation instructions. The `Package` struct in [`types.rs`](https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi/-/blob/main/src/pkg/types.rs) shows all available fields. For more info about creating and publishing a package please visit [this guide](/docs/zds/zoi/creating-packages).
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="How do I publish a package?">
    If the package maintainer has provided a `man` URL in the package definition, you can run `zoi man <package-name>` to view it in your terminal.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="How do I view a package's manual?">
    If the package maintainer has provided a `man` URL in the package definition, you can run `zoi man <package-name>` to view it in your terminal.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="How do optional dependencies work?">
    You can specify `optional` dependencies in your `.pkg.lua` file under the `build`
    or `runtime` sections. When a user installs your package, they will be shown
    the list of optional dependencies and their descriptions, and they can choose which ones to install.
    This is great for plugins or extra features.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="How do I add a new repository?">
    You can add a new repository using the `zoi repo add` command. You can run
    it without arguments for an interactive prompt, or provide the name of the
    repository to add it directly.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="What platforms does Zoi support?">
    Zoi is designed to be cross-platform. For a detailed list of supported
    operating systems and architectures, please refer to the
    "[Platforms](#platforms)" section.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="Can I install packages from other package managers?">
    Yes, Zoi supports installing dependencies from a wide range of other package
    managers like `brew`, `winget`, `scoop`, `npm`, `cargo`, `pip`, and many
    more. These are defined in the `dependencies` section of a packags's
    `.pkg.lua` file.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="How do I install a specific version or channel?">
    You can append a version or channel after an '@' in the source string.
    Examples: `zoi install my-app@1.2.3` or use channels defined in
    `versions` like `my-app@stable`. You can also pin a resolved
    version to prevent updates: `zoi pin my-app VERSION` and later
    `zoi unpin my-app`.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="How do I run a tool without installing it?">
    Use `zoi exec <package>`. Zoi will fetch a temporary binary and run it
    without adding it to your PATH or installed set.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="How do I use a custom git package repository?">
    Add it with `zoi repo add https://github.com/you/your-zoi-repo.git`.
    Install packages from it using `@git/<repo-name>/<pkg-name>`.
    List/remove cloned git repos with `zoi repo git ls` and
    `zoi repo git rm <repo-name>`.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="Where are binaries installed and how do I fix PATH?">
    Binaries are placed in `~/.zoi/pkgs/store/<name>/bin` and linked into
    `~/.zoi/pkgs/bin`. Zoi attempts to add this to your shell PATH on Unix and user PATH on Windows.
    If commands are not found, run `zoi setup` to configure your shell, or add `~/.zoi/pkgs/bin` to your PATH manually.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="How do I accept all prompts (non-interactive)?">
    Pass `--yes` to installation commands to auto-accept confirmations and optional dependency prompts. To install all optional dependencies without being prompted, use `--all-optional`.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="How do I install from a nested repository path?">
    Use the full path in the source, e.g. `@core/linux/amd64/nvidia-driver`.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="How do I update Zoi itself?">
    Run `zoi upgrade`. Zoi attempts a patch (delta) upgrade first and falls back to a full binary download if needed. You can use `zoi upgrade --full` to force a full download, `zoi upgrade --force` to upgrade even if you are on the latest version, and `zoi upgrade --tag <tag>` or `zoi upgrade --branch <branch>` to target a specific release.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="How do I rollback a package update?">
    If an update causes issues, you can revert to the previously installed version using `zoi rollback <package-name>`. Zoi automatically creates a backup before upgrading a package. For more details, see the [Package Rollbacks](/docs/zds/zoi/rollbacks) guide.
  </Accordion>
</Accordions>
<br />
<Accordions type="single">
  <Accordion title="How can I back up and restore my installed packages?">
    Zoi automatically keeps a record of all your installed packages in an SBOM file at `~/.zoi/pkgs/zoi.pkgs.json`. You can back up this file. To restore all your packages on a new system, simply run `zoi install /path/to/your/zoi.pkgs.json`.
  </Accordion>
</Accordions>

<br />
<Accordions type="single">
  <Accordion title="Does Zoi collect your data?">
    We believe in privacy by design. Zoi does **not** collect any data by
    default. You can choose to opt-in to our anonymous telemetry to help us
    improve the application. To learn more about what we collect and why, please
    see our [Telemetry & Analytics](/docs/zds/zoi/telemetry) page.
  </Accordion>
</Accordions>

## Examples

- **Install a package:**

  ```sh
  zoi install <package_name>
  ```

- **Install multiple packages:**

  ```sh
  zoi install <package_1> <package_2>
  ```

- **Update a package:**

  ```sh
  zoi update <package_name>
  ```

- **Update multiple packages:**

  ```sh
  zoi update <package_1> <package_2>
  ```

- **Update all packages:**

  ```sh
  zoi update all
  ```

- **Uninstall a package:**

  ```sh
  zoi uninstall <package_name>
  ```

- **Uninstall multiple packages:**

  ```sh
  zoi uninstall <package_1> <package_2>
  ```

- **Install from a specific repository:**

  ```sh
  # Install from a top-level repository
  zoi install @community/htop

  # Install from a nested repository
  zoi install @core/linux/amd64/nvidia-driver
  ```

- **List all available packages from active repos:**

  ```sh
  zoi list --all
  ```

- **Search for a package:**

  ```sh
  zoi search <term>
  ```

- **Search by tag directly:**

  ```sh
  # The term matches tags too
  zoi search editor

  # Require specific tag(s)
  zoi search editor -t cli,devtools
  zoi search editor -t cli -t devtools
  ```

- **Check why a package is installed:**

  ```sh
  zoi why <package_name>
  ```

- **Create an app from a template:**

  ```sh
  zoi create <source> <appName>
  # e.g.
  zoi create rails-app MyBlog
  zoi create @community/rails-app MyBlog
  ```

  ```sh
  # The term matches tags too
  zoi search editor

  # Require specific tag(s)
  zoi search editor -t cli,devtools
  zoi search editor -t cli -t devtools
  ```

- **Check why a package is installed:**

  ```sh
  zoi why <package_name>
  ```

- **Create an app from a template:**
  ```sh
  zoi create <source> <appName>
  # e.g.
  zoi create rails-app MyBlog
  zoi create @community/rails-app MyBlog
  ```
